readme.taskfer

Taskfer (a.k.a. todo) is a simple command-line task manager that
runs in bash.

Copyright 2010 fsmithred at gmail dot com
License: Artistic License 2.0
(http://www.perlfoundation.org/artistic_license_2_0)


_INSTALLATION_

Easy way:
    tar -xvzf taskfer<version>
    cd taskfer<version>
    ./taskfer_setup
    todo -h

Manual setup:
The executable script is named todo for easy typing. Put it in your 
path ($HOME/bin is a good choice), or run from the current directory as
  ./todo [option]

Put taskferrc in $HOME/.taskfer (or don't. this is optional.)
Edit taskferrc to customize the paths.

Edit the taskfer_dir variable in the main script if you want 
the config and working files in some other directory.
It's near the beginning, and it looks like this:
taskfer_dir=$HOME/.taskfer


_USING TASKFER_

ADD TASKS TO THE LIST

There are three ways to make an entry:

1. Use the -i option (interactive)
Script asks you to enter tag, date and message, one
item at a time. (See below for more information about entries.) 

2. Use the -a option (add/append)
    todo -a  <tag>  <date>  <message text>

All information you want to enter goes on the command line. Leave
a space between each field. Free-form dates with spaces, like 
"next week" or "Nov 15" need to be quoted. The message text may or 
may not need quotes, depending on what symbols it contains. 
Parentheses and semi-colons are known to be a problem; if you use them,
quote the whole text message.

If the date is in the past, you will be asked if you want to continue.
All fields must be entered. If you forget a tag or a date, you'll get
the wrong information in that field in the task list.

3. Use no option
Run the script with no options, and you will be prompted to enter
a tag, a date, and a message, all on one line, separated by semi-colons. 
Spaces don't matter, but be consistent about whether you use a space
before and after the semi-colon, so your fields line up when you recall
them. Nothing needs to be quoted. It is now safe to use colons in the 
message field. (starting with version .04.1)

After you enter the item, you are presented with the entry screen again.
To exit this screen hit the enter key without typing anthing.

4. Use the -r option to enter a recurrent task. You will be prompted to
enter all fields, separated by semi-colons. Fields are tag, date, text,
number of times the event repeats, and length of time between the events
(days, weeks, months).

A note about tags:
Tags can be up to six characters long without messing up the alignment
of the fields on recall. Longer tags will work, but the result won't
look as nice.

5. Add items that don't have a due date by putting n or none in the
due date field. (The script will convert any word beginning with "n" to
"none".)


RECALL/DISPLAY TASKS

todo <option> [argument]


-l, --list
Displays all entries using the pager (default pager is less.) Entries
are sorted by date, with the oldest dates at the top.

-d, --due <due date>
Diplays all entries due on the specified date along with a popup 
calendar. If no date is specified, todays tasks will be displayed. 
Entries are sorted by tag, in alphanumeric order. (numbers first) 
Dates with spaces don't need to be quoted here. For example, 

  todo -d next week 

will show entries with due date one week from today.

-dc <due date>
Same as -d above, but with the calendar inline, for console mode.

-w, --week [n]
Shows all tasks due for the next n days with popup calendar. If n is 
ommitted, the next week (today plus 7 days) will be displayed.

-wc [n]
Same as -w above, but with the calendar inline, for console mode.

-t, --tag <tag> 
Displays all entries that have the specified tag. Entries are sorted
by date, with the oldest dates at the top.

-tc <tag>
Same as -t above, but with the calendar inline, for console mode.

-k, --key, --keyword <keyword>
Displays all entries that contain the specified key word or phrase
anywhere in the entry, including tags and dates.

-n, --none
displays all entries that have "none" in the due date field.


REMOVE TASKS FROM THE LIST

-x, --del
Displays the entire tasklist with numbered lines and asks which line
to delete, then asks if you want to delete another line. A yes answer
displays the edited list and asks which line to delete. Quits when you 
answer with other than y or Y.

-xr, --rdel
Same as -x, --del, but entries are displayed in reverse order.

-clean
Removes all entries with due date older than today.

-e, --edit
Opens the tasklist in a text editor. The default is nano and can be 
changed by editing taskferrc.

-h, --help -?
Shows a brief help message.

-v, --version
Displays version information.


AUTOMATIC NOTIFICATION

There are a few ways to get taskfer to remind you automatically that you
have tasks listed for the day (or the week.)

If you log in to a command line environment:
Put a line like this in your .profile, and you'll get to see your tasks
for the week when you log in. Change "todo -wc" to "todo -dc" to get
the task list for today only. 

echo -e "\n\n" && todo -wc  && echo -e "\n today is: \n $(date +%F) \n"

or simply add:

todo -wc


If you're in a graphical environment, you can use taskfer-notify to give
you a popup window alerting you that there are tasks due today. You
must have libnotify-bin installed (in Debian), and you must put the
taskfer-notify script in your path.

To get the popup when you log in to your desktop, add taskfer-notify
to your startup applications in whatever desktop you're using. 

Another way would be to make a wrapper script for some application that
you normally run by clicking on a panel button. Edit the button
properties to run a script like the following, make the script
executable, and put it in your path.

Example:
#!/usr/bin/env bash
# start-iceweasel

$HOME/bin/taskfer-notify
iceweasel

exit 0

